CopycURL Copied Copy failed

#!/usr/bin/env bash
# Bill a customer on a schedule
#
# Charge a new subscriber, keep their card, and put them on a monthly contract the platform bills
# for you, instead of running the schedule from your own service.
#
# Every API call in this blueprint, in order. Each value a call returns is passed to the calls after
# it. A step that happens outside the API is a comment, and any failed call stops the script.

set -euo pipefail

BASE_URL="{{BASE_URL}}"
API_KEY="{{API_KEY}}"

# Values you supply. Set each one before you run the script.
# The name the customer is created under, and the name on their contact detail. You choose it, so
# nothing reads it off a response.
customerName=""

# Sends one request and prints the response body. A failed call prints the API's answer and stops
# the script.
call() {
  local method="$1" path="$2" body="${3:-}" out
  local args=(-sS --fail-with-body -X "$method" "$BASE_URL$path" -H "api-key: $API_KEY")
  if [ -n "$body" ]; then
    args+=(-H "Content-Type: application/json" -d "$body")
  fi
  if ! out=$(curl "${args[@]}"); then
    printf '%s\n' "$out" >&2
    return 1
  fi
  printf '%s' "$out"
}

# Percent-encodes a value for use in a URL.
urlencode() {
  jq -rn --arg value "$1" '$value | @uri'
}

# Phase 1: Charge the first period

# Step 1: Charge the first period at signup
step1=$(call POST "/api/transactions" '{
  "transactionType": "Sale",
  "cardData": {
    "cardNumber": "4111111111111111",
    "nameOnCard": "Jane Doe",
    "expirationMonth": 12,
    "expirationYear": 2030,
    "cvv": 123
  },
  "invoiceData": {
    "amounts": { "base": 10.00, "total": 10.00 }
  }
}')
merchantId=$(jq -er '.merchantId | if . == null then error("The response carried no value for merchantId.") else tostring end' <<< "$step1")

# Phase 2: Set the customer up

# Step 2: Choose a name for the subscriber
# Pick the name the customer record is created under. It has to be unique within the merchant: this
# platform refuses a second customer with a name another one already holds, and answers "Customer
# name must be unique within the same merchant." That's why the page asks rather than showing one,
# and why a sandbox merchant other people work through has names on it already. Use a fresh one each
# time you come back here, and in your own integration use whatever your system calls the
# subscriber.

# Step 3: Create the customer the schedule belongs to
body=$(jq -n --arg merchantId "$merchantId" --arg customerName "$customerName" '{
  "merchantId": $merchantId,
  "name": $customerName,
  "isActive": true,
  "contactDetail": {
    "primaryContactName": $customerName,
    "emailAddress": "jane.doe@example.com",
    "phone": "5555550123",
    "addresses": [
      {
        "address1": "100 Main Street",
        "city": "Minneapolis",
        "state": "MN",
        "zip": "55401",
        "isDefault": true
      }
    ]
  }
}')
step3=$(call POST "/api/customers" "$body")
customerId=$(jq -er '.id | if . == null then error("The response carried no value for customerId.") else tostring end' <<< "$step3")
scheduleStartDate=$(jq -er '.creationTime | if . == null then error("The response carried no value for scheduleStartDate.") else tostring end' <<< "$step3")

# Step 4: Store the customer's card for the renewals
step4=$(call POST "/api/customers/add-stored-payment-method-async?customerId=$(urlencode "$customerId")" '{
  "paymentMethodType": "Card",
  "customName": "Subscription card",
  "isDefault": true,
  "cardData": {
    "cardNumber": "4111111111111111",
    "nameOnCard": "Jane Doe",
    "expirationMonth": 12,
    "expirationYear": 2030,
    "cvv": 123
  }
}')
savedCardToken=$(jq -er '.publicReference | if . == null then error("The response carried no value for savedCardToken.") else tostring end' <<< "$step4")

# Phase 3: Put them on a schedule

# Step 5: Create the contract that carries the schedule
body=$(jq -n --arg customerId "$customerId" --arg savedCardToken "$savedCardToken" --arg scheduleStartDate "$scheduleStartDate" '{
  "name": "Monthly subscription",
  "customerId": $customerId,
  "isActive": true,
  "payMethod": {
    "type": "Card",
    "paymentTokenReference": $savedCardToken
  },
  "perBillInvoice": {
    "billSubtotalAmount": 10.00,
    "taxAmount": 0.00,
    "totalAmount": 10.00
  },
  "schedule": {
    "frequency": "Monthly",
    "interval": 1,
    "startDate": $scheduleStartDate
  }
}')
step5=$(call POST "/api/contracts" "$body")
contractId=$(jq -er '.id | if . == null then error("The response carried no value for contractId.") else tostring end' <<< "$step5")

# Phase 4: Watch the schedule run

# Step 6: Ask an administrator to run the schedule now
# The schedule runs on the platform's own timer, so a live contract needs nothing further from you.
# To watch a run happen rather than wait for one, an administrator can start one on demand and
# narrow it to a single contract. This call is gated on an administrative permission, so your
# integration key can't make it and this platform doesn't run this step for you. Bring it to whoever
# administers the account.

# Step 7: Read what the run did to this contract
# Each run comes back with the contracts it touched, what it charged and what it couldn't. Read it
# to reconcile a billing day rather than inferring the outcome from your own records. This call is
# gated on the same administrative permission as the trigger above, so it's documented here rather
# than run for you. For the signal your own integration should act on, subscribe to the transaction
# webhooks instead: a contract charge raises the same events an ordinary sale does.

# Step 8: When the subscription ends
# Cancelling a subscription is two things, and doing only the first is the common mistake.
# Deactivate the contract so the schedule stops, and retire the stored payment method so the card
# you were given permission to keep stops being kept. "Save a card and charge it later" covers the
# retirement end to end, including why deactivating beats deleting once any transaction references
# the handle.

CopyPowerShell Copied Copy failed

# Bill a customer on a schedule
#
# Charge a new subscriber, keep their card, and put them on a monthly contract the platform bills
# for you, instead of running the schedule from your own service.
#
# Every API call in this blueprint, in order. Each value a call returns is passed to the calls after
# it. A step that happens outside the API is a comment, and any failed call stops the script.

$ErrorActionPreference = 'Stop'

$baseUrl = '{{BASE_URL}}'
$apiKey = '{{API_KEY}}'

# Values you supply. Set each one before you run the script.
# The name the customer is created under, and the name on their contact detail. You choose it, so
# nothing reads it off a response.
$customerName = ''

# Sends one request and returns the parsed response body. A failed call stops the script.
function Invoke-BlueprintCall([string] $Method, [string] $Path, [string] $Body) {
    $arguments = @{
        Method  = $Method
        Uri     = $baseUrl + $Path
        Headers = @{ 'api-key' = $apiKey }
    }
    if ($Body) {
        $arguments.ContentType = 'application/json'
        $arguments.Body = [System.Text.Encoding]::UTF8.GetBytes($Body)
    }
    Invoke-RestMethod @arguments
}

# Turns a value read off a response back into the text the API sent. A missing value stops the
# script.
function ConvertTo-CaptureValue($Value, [string] $Name) {
    if ($null -eq $Value) { throw "The response carried no value for $Name." }
    if ($Value -is [datetime] -and $Value.Kind -eq 'Unspecified') { return $Value.ToString('yyyy-MM-ddTHH:mm:ss.FFFFFFF', [cultureinfo]::InvariantCulture) }
    if ($Value -is [datetime]) { return $Value.ToUniversalTime().ToString('o') }
    if ($Value -is [bool]) { return $Value.ToString().ToLowerInvariant() }
    [string]$Value
}

# Phase 1: Charge the first period

# Step 1: Charge the first period at signup
$body = @'
{
  "transactionType": "Sale",
  "cardData": {
    "cardNumber": "4111111111111111",
    "nameOnCard": "Jane Doe",
    "expirationMonth": 12,
    "expirationYear": 2030,
    "cvv": 123
  },
  "invoiceData": {
    "amounts": { "base": 10.00, "total": 10.00 }
  }
}
'@
$step1 = Invoke-BlueprintCall -Method 'POST' -Path '/api/transactions' -Body $body
$merchantId = ConvertTo-CaptureValue $step1.merchantId 'merchantId'

# Phase 2: Set the customer up

# Step 2: Choose a name for the subscriber
# Pick the name the customer record is created under. It has to be unique within the merchant: this
# platform refuses a second customer with a name another one already holds, and answers "Customer
# name must be unique within the same merchant." That's why the page asks rather than showing one,
# and why a sandbox merchant other people work through has names on it already. Use a fresh one each
# time you come back here, and in your own integration use whatever your system calls the
# subscriber.

# Step 3: Create the customer the schedule belongs to
$body = @"
{
  "merchantId": $(ConvertTo-Json -InputObject ([string]($merchantId))),
  "name": $(ConvertTo-Json -InputObject ([string]($customerName))),
  "isActive": true,
  "contactDetail": {
    "primaryContactName": $(ConvertTo-Json -InputObject ([string]($customerName))),
    "emailAddress": "jane.doe@example.com",
    "phone": "5555550123",
    "addresses": [
      {
        "address1": "100 Main Street",
        "city": "Minneapolis",
        "state": "MN",
        "zip": "55401",
        "isDefault": true
      }
    ]
  }
}
"@
$step3 = Invoke-BlueprintCall -Method 'POST' -Path '/api/customers' -Body $body
$customerId = ConvertTo-CaptureValue $step3.id 'customerId'
$scheduleStartDate = ConvertTo-CaptureValue $step3.creationTime 'scheduleStartDate'

# Step 4: Store the customer's card for the renewals
$body = @'
{
  "paymentMethodType": "Card",
  "customName": "Subscription card",
  "isDefault": true,
  "cardData": {
    "cardNumber": "4111111111111111",
    "nameOnCard": "Jane Doe",
    "expirationMonth": 12,
    "expirationYear": 2030,
    "cvv": 123
  }
}
'@
$step4 = Invoke-BlueprintCall -Method 'POST' -Path "/api/customers/add-stored-payment-method-async?customerId=$([uri]::EscapeDataString($customerId))" -Body $body
$savedCardToken = ConvertTo-CaptureValue $step4.publicReference 'savedCardToken'

# Phase 3: Put them on a schedule

# Step 5: Create the contract that carries the schedule
$body = @"
{
  "name": "Monthly subscription",
  "customerId": $(ConvertTo-Json -InputObject ([string]($customerId))),
  "isActive": true,
  "payMethod": {
    "type": "Card",
    "paymentTokenReference": $(ConvertTo-Json -InputObject ([string]($savedCardToken)))
  },
  "perBillInvoice": {
    "billSubtotalAmount": 10.00,
    "taxAmount": 0.00,
    "totalAmount": 10.00
  },
  "schedule": {
    "frequency": "Monthly",
    "interval": 1,
    "startDate": $(ConvertTo-Json -InputObject ([string]($scheduleStartDate)))
  }
}
"@
$step5 = Invoke-BlueprintCall -Method 'POST' -Path '/api/contracts' -Body $body
$contractId = ConvertTo-CaptureValue $step5.id 'contractId'

# Phase 4: Watch the schedule run

# Step 6: Ask an administrator to run the schedule now
# The schedule runs on the platform's own timer, so a live contract needs nothing further from you.
# To watch a run happen rather than wait for one, an administrator can start one on demand and
# narrow it to a single contract. This call is gated on an administrative permission, so your
# integration key can't make it and this platform doesn't run this step for you. Bring it to whoever
# administers the account.

# Step 7: Read what the run did to this contract
# Each run comes back with the contracts it touched, what it charged and what it couldn't. Read it
# to reconcile a billing day rather than inferring the outcome from your own records. This call is
# gated on the same administrative permission as the trigger above, so it's documented here rather
# than run for you. For the signal your own integration should act on, subscribe to the transaction
# webhooks instead: a contract charge raises the same events an ordinary sale does.

# Step 8: When the subscription ends
# Cancelling a subscription is two things, and doing only the first is the common mistake.
# Deactivate the contract so the schedule stops, and retire the stored payment method so the card
# you were given permission to keep stops being kept. "Save a card and charge it later" covers the
# retirement end to end, including why deactivating beats deleting once any transaction references
# the handle.

CopyTypeScript Copied Copy failed

// Bill a customer on a schedule
//
// Charge a new subscriber, keep their card, and put them on a monthly contract the platform bills
// for you, instead of running the schedule from your own service.
//
// Every API call in this blueprint, in order. Each value a call returns is passed to the calls
// after it. A step that happens outside the API is a comment, and any failed call stops the script.

export {};

const baseUrl = '{{BASE_URL}}';
const apiKey = '{{API_KEY}}';

// Values you supply. Set each one before you run the script.
// The name the customer is created under, and the name on their contact detail. You choose it, so
// nothing reads it off a response.
const customerName = '';

// Sends one request and returns the parsed response body. A failed call throws.
async function call(method: string, path: string, body?: unknown): Promise<any> {
  const headers: Record<string, string> = { 'api-key': apiKey };
  if (body !== undefined) {
    headers['Content-Type'] = 'application/json';
  }

  const response = await fetch(baseUrl + path, {
    method,
    headers,
    body: body === undefined ? undefined : JSON.stringify(body),
  });

  const text = await response.text();
  if (!response.ok) {
    throw new Error(`${method} ${path} answered ${response.status}: ${text}`);
  }

  return text ? JSON.parse(text) : null;
}

// Turns a value read off a response into the text the API sent. A missing value throws.
function capture(value: unknown, name: string): string {
  if (value === undefined || value === null) {
    throw new Error(`The response carried no value for ${name}.`);
  }

  return typeof value === 'string' ? value : JSON.stringify(value);
}

// Phase 1: Charge the first period

// Step 1: Charge the first period at signup
const step1 = await call('POST', '/api/transactions', {
  "transactionType": "Sale",
  "cardData": {
    "cardNumber": "4111111111111111",
    "nameOnCard": "Jane Doe",
    "expirationMonth": 12,
    "expirationYear": 2030,
    "cvv": 123
  },
  "invoiceData": {
    "amounts": { "base": 10.00, "total": 10.00 }
  }
});
const merchantId = capture(step1.merchantId, 'merchantId');

// Phase 2: Set the customer up

// Step 2: Choose a name for the subscriber
// Pick the name the customer record is created under. It has to be unique within the merchant: this
// platform refuses a second customer with a name another one already holds, and answers "Customer
// name must be unique within the same merchant." That's why the page asks rather than showing one,
// and why a sandbox merchant other people work through has names on it already. Use a fresh one
// each time you come back here, and in your own integration use whatever your system calls the
// subscriber.

// Step 3: Create the customer the schedule belongs to
const step3 = await call('POST', '/api/customers', {
  "merchantId": merchantId,
  "name": customerName,
  "isActive": true,
  "contactDetail": {
    "primaryContactName": customerName,
    "emailAddress": "jane.doe@example.com",
    "phone": "5555550123",
    "addresses": [
      {
        "address1": "100 Main Street",
        "city": "Minneapolis",
        "state": "MN",
        "zip": "55401",
        "isDefault": true
      }
    ]
  }
});
const customerId = capture(step3.id, 'customerId');
const scheduleStartDate = capture(step3.creationTime, 'scheduleStartDate');

// Step 4: Store the customer's card for the renewals
const step4 = await call('POST', `/api/customers/add-stored-payment-method-async?customerId=${encodeURIComponent(customerId)}`, {
  "paymentMethodType": "Card",
  "customName": "Subscription card",
  "isDefault": true,
  "cardData": {
    "cardNumber": "4111111111111111",
    "nameOnCard": "Jane Doe",
    "expirationMonth": 12,
    "expirationYear": 2030,
    "cvv": 123
  }
});
const savedCardToken = capture(step4.publicReference, 'savedCardToken');

// Phase 3: Put them on a schedule

// Step 5: Create the contract that carries the schedule
const step5 = await call('POST', '/api/contracts', {
  "name": "Monthly subscription",
  "customerId": customerId,
  "isActive": true,
  "payMethod": {
    "type": "Card",
    "paymentTokenReference": savedCardToken
  },
  "perBillInvoice": {
    "billSubtotalAmount": 10.00,
    "taxAmount": 0.00,
    "totalAmount": 10.00
  },
  "schedule": {
    "frequency": "Monthly",
    "interval": 1,
    "startDate": scheduleStartDate
  }
});
const contractId = capture(step5.id, 'contractId');

// Phase 4: Watch the schedule run

// Step 6: Ask an administrator to run the schedule now
// The schedule runs on the platform's own timer, so a live contract needs nothing further from you.
// To watch a run happen rather than wait for one, an administrator can start one on demand and
// narrow it to a single contract. This call is gated on an administrative permission, so your
// integration key can't make it and this platform doesn't run this step for you. Bring it to
// whoever administers the account.

// Step 7: Read what the run did to this contract
// Each run comes back with the contracts it touched, what it charged and what it couldn't. Read it
// to reconcile a billing day rather than inferring the outcome from your own records. This call is
// gated on the same administrative permission as the trigger above, so it's documented here rather
// than run for you. For the signal your own integration should act on, subscribe to the transaction
// webhooks instead: a contract charge raises the same events an ordinary sale does.

// Step 8: When the subscription ends
// Cancelling a subscription is two things, and doing only the first is the common mistake.
// Deactivate the contract so the schedule stops, and retire the stored payment method so the card
// you were given permission to keep stops being kept. "Save a card and charge it later" covers the
// retirement end to end, including why deactivating beats deleting once any transaction references
// the handle.

CopyC# Copied Copy failed

// Bill a customer on a schedule
//
// Charge a new subscriber, keep their card, and put them on a monthly contract the platform bills
// for you, instead of running the schedule from your own service.
//
// Every API call in this blueprint, in order. Each value a call returns is passed to the calls
// after it. A step that happens outside the API is a comment, and any failed call stops the script.

using System.Text;
using System.Text.Json;

var baseUrl = "{{BASE_URL}}";
var apiKey = "{{API_KEY}}";

// Values you supply. Set each one before you run the script.
// The name the customer is created under, and the name on their contact detail. You choose it, so
// nothing reads it off a response.
var customerName = "";

using var http = new HttpClient();
http.DefaultRequestHeaders.Add("api-key", apiKey);

// Sends one request and returns the parsed response body. A failed call throws.
async Task<JsonElement> CallAsync(string method, string path, string? body = null)
{
    using var request = new HttpRequestMessage(new HttpMethod(method), baseUrl + path);
    if (body is not null)
    {
        request.Content = new StringContent(body, Encoding.UTF8, "application/json");
    }

    using var response = await http.SendAsync(request);
    var json = await response.Content.ReadAsStringAsync();
    if (!response.IsSuccessStatusCode)
    {
        throw new HttpRequestException($"{method} {path} answered {(int)response.StatusCode}: {json}");
    }

    return json.Length == 0 ? default : JsonSerializer.Deserialize<JsonElement>(json);
}

// Turns a value read off a response into the text the API sent. A missing value throws.
static string Capture(JsonElement value, string name) => value.ValueKind switch
{
    JsonValueKind.String => value.GetString()!,
    JsonValueKind.Number or JsonValueKind.True or JsonValueKind.False => value.GetRawText(),
    _ => throw new InvalidOperationException($"The response carried no value for {name}.")
};

// Phase 1: Charge the first period

// Step 1: Charge the first period at signup
var step1 = await CallAsync("POST", "/api/transactions", """
    {
      "transactionType": "Sale",
      "cardData": {
        "cardNumber": "4111111111111111",
        "nameOnCard": "Jane Doe",
        "expirationMonth": 12,
        "expirationYear": 2030,
        "cvv": 123
      },
      "invoiceData": {
        "amounts": { "base": 10.00, "total": 10.00 }
      }
    }
    """);
var merchantId = Capture(step1.GetProperty("merchantId"), "merchantId");

// Phase 2: Set the customer up

// Step 2: Choose a name for the subscriber
// Pick the name the customer record is created under. It has to be unique within the merchant: this
// platform refuses a second customer with a name another one already holds, and answers "Customer
// name must be unique within the same merchant." That's why the page asks rather than showing one,
// and why a sandbox merchant other people work through has names on it already. Use a fresh one
// each time you come back here, and in your own integration use whatever your system calls the
// subscriber.

// Step 3: Create the customer the schedule belongs to
var step3 = await CallAsync("POST", "/api/customers", $$"""
    {
      "merchantId": {{JsonSerializer.Serialize(merchantId)}},
      "name": {{JsonSerializer.Serialize(customerName)}},
      "isActive": true,
      "contactDetail": {
        "primaryContactName": {{JsonSerializer.Serialize(customerName)}},
        "emailAddress": "jane.doe@example.com",
        "phone": "5555550123",
        "addresses": [
          {
            "address1": "100 Main Street",
            "city": "Minneapolis",
            "state": "MN",
            "zip": "55401",
            "isDefault": true
          }
        ]
      }
    }
    """);
var customerId = Capture(step3.GetProperty("id"), "customerId");
var scheduleStartDate = Capture(step3.GetProperty("creationTime"), "scheduleStartDate");

// Step 4: Store the customer's card for the renewals
var step4 = await CallAsync("POST", $"/api/customers/add-stored-payment-method-async?customerId={Uri.EscapeDataString(customerId)}", """
    {
      "paymentMethodType": "Card",
      "customName": "Subscription card",
      "isDefault": true,
      "cardData": {
        "cardNumber": "4111111111111111",
        "nameOnCard": "Jane Doe",
        "expirationMonth": 12,
        "expirationYear": 2030,
        "cvv": 123
      }
    }
    """);
var savedCardToken = Capture(step4.GetProperty("publicReference"), "savedCardToken");

// Phase 3: Put them on a schedule

// Step 5: Create the contract that carries the schedule
var step5 = await CallAsync("POST", "/api/contracts", $$"""
    {
      "name": "Monthly subscription",
      "customerId": {{JsonSerializer.Serialize(customerId)}},
      "isActive": true,
      "payMethod": {
        "type": "Card",
        "paymentTokenReference": {{JsonSerializer.Serialize(savedCardToken)}}
      },
      "perBillInvoice": {
        "billSubtotalAmount": 10.00,
        "taxAmount": 0.00,
        "totalAmount": 10.00
      },
      "schedule": {
        "frequency": "Monthly",
        "interval": 1,
        "startDate": {{JsonSerializer.Serialize(scheduleStartDate)}}
      }
    }
    """);
var contractId = Capture(step5.GetProperty("id"), "contractId");

// Phase 4: Watch the schedule run

// Step 6: Ask an administrator to run the schedule now
// The schedule runs on the platform's own timer, so a live contract needs nothing further from you.
// To watch a run happen rather than wait for one, an administrator can start one on demand and
// narrow it to a single contract. This call is gated on an administrative permission, so your
// integration key can't make it and this platform doesn't run this step for you. Bring it to
// whoever administers the account.

// Step 7: Read what the run did to this contract
// Each run comes back with the contracts it touched, what it charged and what it couldn't. Read it
// to reconcile a billing day rather than inferring the outcome from your own records. This call is
// gated on the same administrative permission as the trigger above, so it's documented here rather
// than run for you. For the signal your own integration should act on, subscribe to the transaction
// webhooks instead: a contract charge raises the same events an ordinary sale does.

// Step 8: When the subscription ends
// Cancelling a subscription is two things, and doing only the first is the common mistake.
// Deactivate the contract so the schedule stops, and retire the stored payment method so the card
// you were given permission to keep stops being kept. "Save a card and charge it later" covers the
// retirement end to end, including why deactivating beats deleting once any transaction references
// the handle.

CopyPython Copied Copy failed

# Bill a customer on a schedule
#
# Charge a new subscriber, keep their card, and put them on a monthly contract the platform bills
# for you, instead of running the schedule from your own service.
#
# Every API call in this blueprint, in order. Each value a call returns is passed to the calls after
# it. A step that happens outside the API is a comment, and any failed call stops the script.

from urllib.parse import quote

import json
import requests

BASE_URL = "{{BASE_URL}}"
API_KEY = "{{API_KEY}}"

# Values you supply. Set each one before you run the script.
# The name the customer is created under, and the name on their contact detail. You choose it, so
# nothing reads it off a response.
customer_name = ""


# Sends one request and returns the parsed response body. A failed call raises.
def call(method, path, body=None):
    response = requests.request(
        method,
        BASE_URL + path,
        headers={"api-key": API_KEY},
        json=body,
    )
    response.raise_for_status()
    return response.json() if response.content else None


# Turns a value read off a response into the text the API sent. A missing value raises.
def capture(value, name):
    if value is None:
        raise ValueError(f"The response carried no value for {name}.")
    return value if isinstance(value, str) else json.dumps(value)


# Phase 1: Charge the first period

# Step 1: Charge the first period at signup
step1 = call("POST", "/api/transactions", {
  "transactionType": "Sale",
  "cardData": {
    "cardNumber": "4111111111111111",
    "nameOnCard": "Jane Doe",
    "expirationMonth": 12,
    "expirationYear": 2030,
    "cvv": 123
  },
  "invoiceData": {
    "amounts": { "base": 10.00, "total": 10.00 }
  }
})
merchant_id = capture(step1["merchantId"], "merchantId")

# Phase 2: Set the customer up

# Step 2: Choose a name for the subscriber
# Pick the name the customer record is created under. It has to be unique within the merchant: this
# platform refuses a second customer with a name another one already holds, and answers "Customer
# name must be unique within the same merchant." That's why the page asks rather than showing one,
# and why a sandbox merchant other people work through has names on it already. Use a fresh one each
# time you come back here, and in your own integration use whatever your system calls the
# subscriber.

# Step 3: Create the customer the schedule belongs to
step3 = call("POST", "/api/customers", {
  "merchantId": merchant_id,
  "name": customer_name,
  "isActive": True,
  "contactDetail": {
    "primaryContactName": customer_name,
    "emailAddress": "jane.doe@example.com",
    "phone": "5555550123",
    "addresses": [
      {
        "address1": "100 Main Street",
        "city": "Minneapolis",
        "state": "MN",
        "zip": "55401",
        "isDefault": True
      }
    ]
  }
})
customer_id = capture(step3["id"], "customerId")
schedule_start_date = capture(step3["creationTime"], "scheduleStartDate")

# Step 4: Store the customer's card for the renewals
step4 = call("POST", f"/api/customers/add-stored-payment-method-async?customerId={quote(customer_id, safe='')}", {
  "paymentMethodType": "Card",
  "customName": "Subscription card",
  "isDefault": True,
  "cardData": {
    "cardNumber": "4111111111111111",
    "nameOnCard": "Jane Doe",
    "expirationMonth": 12,
    "expirationYear": 2030,
    "cvv": 123
  }
})
saved_card_token = capture(step4["publicReference"], "savedCardToken")

# Phase 3: Put them on a schedule

# Step 5: Create the contract that carries the schedule
step5 = call("POST", "/api/contracts", {
  "name": "Monthly subscription",
  "customerId": customer_id,
  "isActive": True,
  "payMethod": {
    "type": "Card",
    "paymentTokenReference": saved_card_token
  },
  "perBillInvoice": {
    "billSubtotalAmount": 10.00,
    "taxAmount": 0.00,
    "totalAmount": 10.00
  },
  "schedule": {
    "frequency": "Monthly",
    "interval": 1,
    "startDate": schedule_start_date
  }
})
contract_id = capture(step5["id"], "contractId")

# Phase 4: Watch the schedule run

# Step 6: Ask an administrator to run the schedule now
# The schedule runs on the platform's own timer, so a live contract needs nothing further from you.
# To watch a run happen rather than wait for one, an administrator can start one on demand and
# narrow it to a single contract. This call is gated on an administrative permission, so your
# integration key can't make it and this platform doesn't run this step for you. Bring it to whoever
# administers the account.

# Step 7: Read what the run did to this contract
# Each run comes back with the contracts it touched, what it charged and what it couldn't. Read it
# to reconcile a billing day rather than inferring the outcome from your own records. This call is
# gated on the same administrative permission as the trigger above, so it's documented here rather
# than run for you. For the signal your own integration should act on, subscribe to the transaction
# webhooks instead: a contract charge raises the same events an ordinary sale does.

# Step 8: When the subscription ends
# Cancelling a subscription is two things, and doing only the first is the common mistake.
# Deactivate the contract so the schedule stops, and retire the stored payment method so the card
# you were given permission to keep stops being kept. "Save a card and charge it later" covers the
# retirement end to end, including why deactivating beats deleting once any transaction references
# the handle.