@whooshbang/contracts 2.3.0 → 2.5.0

package/schemas/whooshbang-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/whooshbang-v1.schema.json",
-  "x-contract-version": "2.3.0",
+  "x-contract-version": "2.5.0",
   "title": "WhooshBangV1ContractDocument",
   "description": "Public request, resource, summary, and Problem Details models for the WhooshBang V1 REST API.",
   "anyOf": [
@@ -394,6 +394,15 @@
     },
     {
       "$ref": "#/$defs/WhoAmI"
+    },
+    {
+      "$ref": "#/$defs/BillingPromotions"
+    },
+    {
+      "$ref": "#/$defs/BillingPromotion"
+    },
+    {
+      "$ref": "#/$defs/RedeemBillingPromotionRequest"
     }
   ],
   "$defs": {
@@ -7029,9 +7038,11 @@
         "billing:write",
         "billing:read",
         "teammates:write",
-        "teammates:read"
+        "teammates:read",
+        "notifications:self",
+        "notifications:team"
       ],
-      "description": "An organization-level capability carried by a human session or an OAuth grant. Teammate scopes reach the organization's people: who is in it, their roles and their projects. Billing scopes grant financial access separately from project configuration. Project and organization API credentials cannot administer billing."
+      "description": "An organization-level capability carried by a human session or an OAuth grant. notifications:self permits only personal operator notifications, own preferences and project discovery. notifications:team additionally permits authorized teammate lookup, direct notifications and predefined operators broadcasts. Notification profiles exclude customer messaging and administration and are requested separately from broader scopes. Teammate scopes reach the organization's people: who is in it, their roles and their projects. Billing scopes grant financial access separately from project configuration. Project and organization API credentials cannot administer billing."
     },
     "OAuthScope": {
       "description": "A scope an OAuth grant may carry. Project-level scopes are the credential vocabulary unchanged; organization-level scopes exist only here and on a human session.",
@@ -10780,6 +10791,12 @@
         "purchase_cents": {
           "type": "integer",
           "enum": [500, 1000, 2500, 5000, 10000]
+        },
+        "approved_charge_usd": {
+          "type": "string",
+          "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{6}$",
+          "maxLength": 40,
+          "description": "Optional. The card charge the customer approved: the pack price less any promotion shown to them. When it differs from what would be charged, the purchase is refused with credit_purchase_price_changed and nothing is charged."
         }
       },
       "description": "Buy one credit pack now with the default card. The amount is the explicit approval of the charge."
@@ -10791,6 +10808,8 @@
         "id",
         "purchase_cents",
         "credit_usd",
+        "charged_usd",
+        "discount_usd",
         "status",
         "failure",
         "client_secret",
@@ -10811,6 +10830,18 @@
           "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{6}$",
           "maxLength": 40
         },
+        "charged_usd": {
+          "type": "string",
+          "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{6}$",
+          "maxLength": 40,
+          "description": "What the card is charged: the pack price less any promotional discount. The pack's credit is unchanged."
+        },
+        "discount_usd": {
+          "type": "string",
+          "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{6}$",
+          "maxLength": 40,
+          "description": "The promotional discount taken off the pack price, or 0.000000."
+        },
         "status": {
           "type": "string",
           "enum": ["processing", "requires_action", "paid", "failed"]
@@ -11404,6 +11435,8 @@
         "monthly_price_usd",
         "charge_now_usd",
         "unused_time_credit_usd",
+        "promotion",
+        "renewal_promotion",
         "effective_at",
         "expires_at",
         "client_secret",
@@ -11465,6 +11498,95 @@
           ],
           "description": "Compatibility field: new upgrades return 0.000000; starts and boundary changes return null. Historical quotes can retain their recorded unused-time credit. No new automatic unused-time refunds or offsets."
         },
+        "promotion": {
+          "anyOf": [
+            {
+              "type": "object",
+              "required": ["percent_off", "duration", "months", "discount_usd"],
+              "properties": {
+                "percent_off": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "maximum": 90
+                },
+                "duration": {
+                  "type": "string",
+                  "enum": ["once", "repeating"]
+                },
+                "months": {
+                  "anyOf": [
+                    {
+                      "type": "integer",
+                      "minimum": 1,
+                      "maximum": 12
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "discount_usd": {
+                  "type": "string",
+                  "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{6}$",
+                  "maxLength": 40,
+                  "description": "What the promotion takes off charge_now_usd."
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "A promotion code's plan discount applied to this first plan or add-on purchase: charge_now_usd is already reduced by it, and the monthly charges keep it for its months. Null when no plan discount applies."
+        },
+        "renewal_promotion": {
+          "anyOf": [
+            {
+              "type": "object",
+              "required": [
+                "percent_off",
+                "duration",
+                "renewal_price_usd",
+                "ends_at"
+              ],
+              "properties": {
+                "percent_off": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "maximum": 90
+                },
+                "duration": {
+                  "type": "string",
+                  "enum": ["once", "repeating"]
+                },
+                "renewal_price_usd": {
+                  "type": "string",
+                  "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{6}$",
+                  "maxLength": 40,
+                  "description": "What the next monthly charge for this selection comes to with the promotion: monthly_price_usd less its percentage."
+                },
+                "ends_at": {
+                  "anyOf": [
+                    {
+                      "type": "string",
+                      "format": "date-time"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ],
+                  "description": "When a repeating promotion stops applying. Null for a once promotion, which applies to the next monthly charge only."
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "A plan discount already running on the subscription, which keeps lowering the monthly charges after this change. It never reduces charge_now_usd. Null when none applies to the next monthly charge, and once a change is no longer a quote."
+        },
         "effective_at": {
           "anyOf": [
             {
@@ -11893,6 +12015,255 @@
         }
       },
       "additionalProperties": false
+    },
+    "BillingPromotion": {
+      "type": "object",
+      "required": [
+        "id",
+        "source",
+        "name",
+        "status",
+        "starts_at",
+        "ends_at",
+        "ended_at",
+        "benefit"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^grn_[0-9a-z]{26}$"
+        },
+        "source": {
+          "type": "string",
+          "enum": ["whooshbang", "code"],
+          "description": "`whooshbang` for a reward WhooshBang gave the organization directly; `code` for a promotion code the organization redeemed."
+        },
+        "name": {
+          "anyOf": [
+            {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 120
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "The promotion's name for a redeemed code. Null for a direct reward."
+        },
+        "status": {
+          "type": "string",
+          "enum": ["active", "pending", "expired", "used", "revoked"],
+          "description": "`pending` is a credit pack discount carried by a payment still waiting for the customer's bank; it is not available to another purchase. `used` applies only to a discount that has been applied to a purchase or put on a plan. `revoked` means WhooshBang withdrew what remained."
+        },
+        "starts_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "ends_at": {
+          "anyOf": [
+            {
+              "type": "string",
+              "format": "date-time"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "When the benefit stops. Null for a discount, which ends when it is used or, for a plan discount, after its months."
+        },
+        "ended_at": {
+          "anyOf": [
+            {
+              "type": "string",
+              "format": "date-time"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "When the promotion was used or withdrawn, if it was."
+        },
+        "benefit": {
+          "oneOf": [
+            {
+              "type": "object",
+              "required": ["kind", "credit_usd", "remaining_usd"],
+              "properties": {
+                "kind": {
+                  "const": "message_credit"
+                },
+                "credit_usd": {
+                  "type": "string",
+                  "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{6}$",
+                  "maxLength": 40
+                },
+                "remaining_usd": {
+                  "type": "string",
+                  "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{6}$",
+                  "maxLength": 40
+                }
+              },
+              "additionalProperties": false,
+              "description": "Promotional credit for messages. Spent before purchased, bonus and welcome credit; it never pays the shared-email charge."
+            },
+            {
+              "type": "object",
+              "required": ["kind", "shared_emails", "remaining"],
+              "properties": {
+                "kind": {
+                  "const": "shared_emails"
+                },
+                "shared_emails": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "maximum": 1000000
+                },
+                "remaining": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 1000000
+                }
+              },
+              "additionalProperties": false,
+              "description": "Emails through WhooshBang's shared email service with no shared-email charge. The message itself is still paid for."
+            },
+            {
+              "type": "object",
+              "required": ["kind"],
+              "properties": {
+                "kind": {
+                  "const": "branding"
+                }
+              },
+              "additionalProperties": false,
+              "description": "WhooshBang branding can be removed from recipient messages until ends_at."
+            },
+            {
+              "type": "object",
+              "required": [
+                "kind",
+                "applies_to",
+                "percent_off",
+                "amount_off_usd",
+                "duration",
+                "months"
+              ],
+              "properties": {
+                "kind": {
+                  "const": "discount"
+                },
+                "applies_to": {
+                  "type": "string",
+                  "enum": ["credit_packs", "subscriptions"]
+                },
+                "percent_off": {
+                  "anyOf": [
+                    {
+                      "type": "integer",
+                      "minimum": 1,
+                      "maximum": 90
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "amount_off_usd": {
+                  "anyOf": [
+                    {
+                      "type": "string",
+                      "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{6}$",
+                      "maxLength": 40
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "duration": {
+                  "type": "string",
+                  "enum": ["once", "repeating"]
+                },
+                "months": {
+                  "anyOf": [
+                    {
+                      "type": "integer",
+                      "minimum": 1,
+                      "maximum": 12
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                }
+              },
+              "additionalProperties": false,
+              "description": "Money off the next credit pack, or off plan and add-on charges for one charge or a number of months."
+            }
+          ]
+        }
+      },
+      "additionalProperties": false,
+      "description": "One promotion an organization holds. Promotional value has no cash value, is never refunded and cannot move to another organization."
+    },
+    "BillingPromotions": {
+      "type": "object",
+      "required": [
+        "promotional_credit_usd",
+        "free_shared_emails",
+        "branding_removed_until",
+        "promotions"
+      ],
+      "properties": {
+        "promotional_credit_usd": {
+          "type": "string",
+          "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{6}$",
+          "maxLength": 40,
+          "description": "Unexpired promotional message credit available now."
+        },
+        "free_shared_emails": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 2147483647,
+          "description": "Unexpired free shared emails available now."
+        },
+        "branding_removed_until": {
+          "anyOf": [
+            {
+              "type": "string",
+              "format": "date-time"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "When the latest active branding promotion ends, if one is active."
+        },
+        "promotions": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/BillingPromotion"
+          },
+          "maxItems": 200
+        }
+      },
+      "additionalProperties": false,
+      "description": "An organization's promotions: rewards WhooshBang gave it and promotion codes it redeemed, newest first."
+    },
+    "RedeemBillingPromotionRequest": {
+      "type": "object",
+      "required": ["code"],
+      "properties": {
+        "code": {
+          "type": "string",
+          "minLength": 4,
+          "maxLength": 64,
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9 _-]*$",
+          "description": "The promotion code. Case, spaces, hyphens and underscores are ignored."
+        }
+      },
+      "additionalProperties": false
     }
   }
 }