merchant api: draft of choices in orders creation

1 files changed, 87 insertions, 0 deletions

diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index ac8e612e..28ca8dab 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -3580,6 +3580,10 @@ The contract terms must have the following structure:
     // encoded in it (such as a short product identifier and timestamp).
     order_id: string;
 
+    // List of contract choices that the customer can select from.
+    // @since protocol **vSUBSCRIBE**
+    choices: ContractChoice[];
+
     // Total price for the transaction.
     // The exchange will subtract deposit fees from that amount
     // before transferring it to the merchant.
@@ -3714,6 +3718,89 @@ The wallet must select an exchange that either the merchant accepts directly by
 listing it in the exchanges array, or for which the merchant accepts an auditor
 that audits that exchange by listing it in the auditors array.
 
+The `ContractChoice` object describes a possible choice within a contract. The
+choice is done by the customer and consists of in- and outputs. In the example
+of buying an article, the merchant could present the customer with the choice
+to use a valid subscription token or pay using a gift voucher. Available since
+protocol **vSUBSCRIBE**.
+
+.. ts:def:: ContractChoice
+
+  interface ContractChoice {
+    // Inputs that must be provided by the customer, if this choice is selected.
+    inputs: ContractInput[];
+
+    // Outputs provided by the merchant, if this choice is selected.
+    outputs: ContractOutput[];
+  }
+
+.. ts:def:: ContractInput
+
+  // For now, only token inputs are supported.
+  type ContractInput = ContractInputToken;
+
+.. ts:def:: ContractInputToken
+
+  interface ContractInputToken {
+
+    // Token input.
+    type: "token";
+
+    // How many units of the input are required. Defaults to 1 if not specified.
+    // Input with number == 0 are ignored by the merchant backend.
+    number?: Integer;
+
+    // Token family slug as configured in the merchant backend. Slug is unique
+    // across all configured tokens of a merchant.
+    token_family_slug: string;
+
+    // TODO: Is this only relevant for subscriptions or also for discounts?
+    // Start of the validity period of the subscription token. Based on this,
+    // the merchant will select the relevant signing key. Is null for discounts.
+    valid_after?: Timestamp;
+
+  }
+
+.. ts:def:: ContractOutput
+
+  type ContractOutput = ContractOutputToken | ContractOutputTaxReceipt;
+
+.. ts:def:: ContractOutputToken
+
+  interface ContractOutputToken {
+
+    // Token output.
+    type: "token";
+
+    // How many units of the output are yielded. Defaults to 1 if not specified.
+    // Output with number == 0 are ignored by the merchant backend.
+    number?: Integer;
+
+    // Token family slug as configured in the merchant backend. Slug is unique
+    // across all configured tokens of a merchant.
+    // TODO: Should we rename this to token_family_slug?
+    authority_label: string;
+
+    // TODO: Is this only relevant for subscriptions or also for discounts?
+    // Start of the validity period of the subscription token. Based on this,
+    // the merchant will select the relevant signing key. Is null for discounts.
+    valid_after?: Timestamp;
+
+  }
+
+.. ts:def:: ContractOutputTaxReceipt
+
+  interface ContractOutputTaxReceipt {
+
+    // Tax receipt output.
+    type: "tax-receipt";
+
+    // Base URL of the donation authority that will
+    // issue the tax receipt.
+    donau_url: string;
+
+  }
+
 The `Product` object describes the product being purchased from the merchant.
 It has the following structure: