GamaEdtech · sanaderi · Jul 18, 2026 · Jul 18, 2026
diff --git a/docs/business/content-delivery.md b/docs/business/content-delivery.md
@@ -126,6 +126,15 @@ authoritative price, there's no reason to trust the client for it here. If the c
 quota, insufficient points), the whole download fails — the URL is not returned, since it was
 never paid for by either side.
 
+On an insufficient-balance failure specifically, `DownloadContentResponseDto`/
+`DownloadContentResponseViewModel.UpgradeSuggestions` carries through the same
+`SpendPointsResponseDto.UpgradeSuggestions` that `games/spends` v2 already exposes (up to 3 plans
+whose `SubscriptionPlanFeature.Limit` would cover this feature), so the download endpoint can drive
+the same "upgrade/top-up" UI instead of a dead-end error. Also, `Localizer["InsufficientBalance"]`
+(`GameService.SpendPointsAsync`) now has a real resx entry
+(`src/Core/Resource/Application/GameService.resx`) — previously it had none anywhere in the repo and
+silently rendered as the literal string `InsufficientBalance` to callers, including this endpoint.
+
 ## Commission accrual
 
 Only runs when `OwnerExternalId` is reported (`PastPaper` only — never `Multimedia`/`Exam`,

diff --git a/src/Application/Service/ContentDeliveryService.cs b/src/Application/Service/ContentDeliveryService.cs
@@ -73,7 +73,11 @@ public async Task<ResultData<DownloadContentResponseDto>> DownloadContentAsync([
                 });
                 if (spendResult.OperationResult is not OperationResult.Succeeded || spendResult.Data?.Spent is not true)
                 {
-                    return new(spendResult.OperationResult) { Errors = spendResult.Errors };
+                    return new(spendResult.OperationResult)
+                    {
+                        Errors = spendResult.Errors,
+                        Data = new() { UpgradeSuggestions = spendResult.Data?.UpgradeSuggestions },
+                    };
                 }
 
                 if (data.OwnerExternalId is not null)

diff --git a/src/Core/Data/Dto/Content/DownloadContentResponseDto.cs b/src/Core/Data/Dto/Content/DownloadContentResponseDto.cs
@@ -1,14 +1,17 @@
 namespace GamaEdtech.Data.Dto.Content
 {
+    using GamaEdtech.Data.Dto.Subscription;
     using GamaEdtech.Domain.Enumeration;
 
     public sealed class DownloadContentResponseDto
     {
-        public required string Url { get; set; }
+        /// <summary>Null when the download didn't happen (e.g. insufficient balance).</summary>
+        public string? Url { get; set; }
         public string? Name { get; set; }
 
         /// <summary>Whether the downloader was charged for this download (false if gama-api already reported it as paid).</summary>
         public bool Spent { get; set; }
         public SpendSource? PaidBy { get; set; }
+        public IEnumerable<UpgradeSuggestionDto>? UpgradeSuggestions { get; set; }
     }
 }
diff --git a/src/Core/Resource/Application/GameService.resx b/src/Core/Resource/Application/GameService.resx
@@ -0,0 +1,123 @@
+<?xml version="1.0" encoding="utf-8"?>
+<root>
+  <!--
+    Microsoft ResX Schema
+
+    Version 2.0
+
+    The primary goals of this format is to allow a simple XML format
+    that is mostly human readable. The generation and parsing of the
+    various data types are done through the TypeConverter classes
+    associated with the data types.
+
+    Example:
+
+    ... ado.net/XML headers & schema ...
+    <resheader name="resmimetype">text/microsoft-resx</resheader>
+    <resheader name="version">2.0</resheader>
+    <resheader name="reader">System.Resources.ResXResourceReader, System.Windows.Forms, ...</resheader>
+    <resheader name="writer">System.Resources.ResXResourceWriter, System.Windows.Forms, ...</resheader>
+    <data name="Name1"><value>this is my long string</value><comment>this is a comment</comment></data>
+    <data name="Color1" type="System.Drawing.Color, System.Drawing">Blue</data>
+    <data name="Bitmap1" mimetype="application/x-microsoft.net.object.binary.base64">
+        <value>[base64 mime encoded serialized .NET Framework object]</value>
+    </data>
+    <data name="Icon1" type="System.Drawing.Icon, System.Drawing" mimetype="application/x-microsoft.net.object.bytearray.base64">
+        <value>[base64 mime encoded string representing a byte array form of the .NET Framework object]</value>
+        <comment>This is a comment</comment>
+    </data>
+
+    There are any number of "resheader" rows that contain simple
+    name/value pairs.
+
+    Each data row contains a name, and value. The row also contains a
+    type or mimetype. Type corresponds to a .NET class that support
+    text/value conversion through the TypeConverter architecture.
+    Classes that don't support this are serialized and stored with the
+    mimetype set.
+
+    The mimetype is used for serialized objects, and tells the
+    ResXResourceReader how to depersist the object. This is currently not
+    extensible. For a given mimetype the value must be set accordingly:
+
+    Note - application/x-microsoft.net.object.binary.base64 is the format
+    that the ResXResourceWriter will generate, however the reader can
+    read any of the formats listed below.
+
+    mimetype: application/x-microsoft.net.object.binary.base64
+    value   : The object must be serialized with
+            : System.Runtime.Serialization.Formatters.Binary.BinaryFormatter
+            : and then encoded with base64 encoding.
+
+    mimetype: application/x-microsoft.net.object.soap.base64
+    value   : The object must be serialized with
+            : System.Runtime.Serialization.Formatters.Soap.SoapFormatter
+            : and then encoded with base64 encoding.
+
+    mimetype: application/x-microsoft.net.object.bytearray.base64
+    value   : The object must be serialized into a byte array
+            : using a System.ComponentModel.TypeConverter
+            : and then encoded with base64 encoding.
+    -->
+  <xsd:schema id="root" xmlns="" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:msdata="urn:schemas-microsoft-com:xml-msdata">
+    <xsd:import namespace="http://www.w3.org/XML/1998/namespace" />
+    <xsd:element name="root" msdata:IsDataSet="true">
+      <xsd:complexType>
+        <xsd:choice maxOccurs="unbounded">
+          <xsd:element name="metadata">
+            <xsd:complexType>
+              <xsd:sequence>
+                <xsd:element name="value" type="xsd:string" minOccurs="0" />
+              </xsd:sequence>
+              <xsd:attribute name="name" use="required" type="xsd:string" />
+              <xsd:attribute name="type" type="xsd:string" />
+              <xsd:attribute name="mimetype" type="xsd:string" />
+              <xsd:attribute ref="xml:space" />
+            </xsd:complexType>
+          </xsd:element>
+          <xsd:element name="assembly">
+            <xsd:complexType>
+              <xsd:attribute name="alias" type="xsd:string" />
+              <xsd:attribute name="name" type="xsd:string" />
+            </xsd:complexType>
+          </xsd:element>
+          <xsd:element name="data">
+            <xsd:complexType>
+              <xsd:sequence>
+                <xsd:element name="value" type="xsd:string" minOccurs="0" msdata:Ordinal="1" />
+                <xsd:element name="comment" type="xsd:string" minOccurs="0" msdata:Ordinal="2" />
+              </xsd:sequence>
+              <xsd:attribute name="name" type="xsd:string" use="required" msdata:Ordinal="1" />
+              <xsd:attribute name="type" type="xsd:string" msdata:Ordinal="3" />
+              <xsd:attribute name="mimetype" type="xsd:string" msdata:Ordinal="4" />
+              <xsd:attribute ref="xml:space" />
+            </xsd:complexType>
+          </xsd:element>
+          <xsd:element name="resheader">
+            <xsd:complexType>
+              <xsd:sequence>
+                <xsd:element name="value" type="xsd:string" minOccurs="0" msdata:Ordinal="1" />
+              </xsd:sequence>
+              <xsd:attribute name="name" type="xsd:string" use="required" />
+            </xsd:complexType>
+          </xsd:element>
+        </xsd:choice>
+      </xsd:complexType>
+    </xsd:element>
+  </xsd:schema>
+  <resheader name="resmimetype">
+    <value>text/microsoft-resx</value>
+  </resheader>
+  <resheader name="version">
+    <value>2.0</value>
+  </resheader>
+  <resheader name="reader">
+    <value>System.Resources.ResXResourceReader, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
+  </resheader>
+  <resheader name="writer">
+    <value>System.Resources.ResXResourceWriter, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
+  </resheader>
+  <data name="InsufficientBalance" xml:space="preserve">
+    <value>You don't have enough points for this. Upgrade your plan or top up your balance.</value>
+  </data>
+</root>
diff --git a/src/Presentation/Api/Controllers/DownloadsController.cs b/src/Presentation/Api/Controllers/DownloadsController.cs
@@ -1,6 +1,7 @@
 namespace GamaEdtech.Presentation.Api.Controllers
 {
     using System.Diagnostics.CodeAnalysis;
+    using System.Linq;
 
     using Asp.Versioning;
 
@@ -10,6 +11,7 @@ namespace GamaEdtech.Presentation.Api.Controllers
     using GamaEdtech.Common.Identity;
     using GamaEdtech.Data.Dto.Content;
     using GamaEdtech.Presentation.ViewModel.Content;
+    using GamaEdtech.Presentation.ViewModel.Game;
 
     using Microsoft.AspNetCore.Mvc;
     using Microsoft.Extensions.Logging;
@@ -57,6 +59,12 @@ public async Task<IActionResult<DownloadContentResponseViewModel>> Download([Not
                         Name = result.Data.Name,
                         Spent = result.Data.Spent,
                         PaidBy = result.Data.PaidBy,
+                        UpgradeSuggestions = result.Data.UpgradeSuggestions?.Select(t => new UpgradeSuggestionViewModel
+                        {
+                            SubscriptionPlanId = t.SubscriptionPlanId,
+                            Title = t.Title,
+                            Limit = t.Limit,
+                        }),
                     },
                 });
             }

diff --git a/src/Presentation/ViewModel/Content/DownloadContentResponseViewModel.cs b/src/Presentation/ViewModel/Content/DownloadContentResponseViewModel.cs
@@ -4,6 +4,7 @@ namespace GamaEdtech.Presentation.ViewModel.Content
 
     using GamaEdtech.Common.Converter;
     using GamaEdtech.Domain.Enumeration;
+    using GamaEdtech.Presentation.ViewModel.Game;
 
     public sealed class DownloadContentResponseViewModel
     {
@@ -13,5 +14,7 @@ public sealed class DownloadContentResponseViewModel
 
         [JsonConverter(typeof(EnumerationConverter<SpendSource, byte>))]
         public SpendSource? PaidBy { get; set; }
+
+        public IEnumerable<UpgradeSuggestionViewModel>? UpgradeSuggestions { get; set; }
     }
 }