Buy stock

View as Markdown

Buys batches of a stock for one of its regions, paid from your wallet only: there is no card top-up, so a short balance buys nothing. Auto-reorder spends from the same wallet, so keep enough balance for both.

What you need

stock_idstringRequired
The stock to buy (stk_...).
region_idstringRequired
Where to produce it (reg_...), one of the stock regions in restock[].region.id of get_stock.
batchesintegerRequired
How many batches; each holds units_per_batch units.
Range at least 1.
idempotency_keystringRequired
A unique string for this attempt, for example a UUID. Send the same value when you retry, so the write happens once.

Step 1: Get a stock

GET/v2/stocks/{id}

Read the stock. Only an approved stock has a price and regions. A batch costs batch_price.

Parameters

{
  "path id": "$inputs.stock_id"
}

Succeeds when:

$statusCode == 200
$response.body#/review/status == 'approved'

Keeps for the next steps:

batch_price: $response.body#/batch_price
units_per_batch: $response.body#/units_per_batch
regions: $response.body#/restock

Step 2: Get your wallet balance

GET/v2/wallet

Read the wallet. The purchase needs batch_price times batches in balance; top up in the dashboard when it is short.

Succeeds when:

$statusCode == 200

Keeps for the next steps:

balance: $response.body#/balance

Step 3: Buy stock batches

POST/v2/stock-purchases

Buy. insufficient_balance (402) comes with details.required and details.balance; nothing was bought. region_not_available (422) means the region is not one of the stock regions.

Parameters

{
  "header Idempotency-Key": "$inputs.idempotency_key"
}

Request body

{
  "items": [
    {
      "stock": "$inputs.stock_id",
      "region": "$inputs.region_id",
      "batches": "$inputs.batches"
    }
  ]
}

Succeeds when:

$statusCode == 201

Otherwise:

retry_server_error: retry after 5 seconds, at most 3 times, when $statusCode >= 500.
insufficient_balance: stop the workflow when $statusCode == 402.
region_not_available: stop the workflow when $statusCode == 422.

Keeps for the next steps:

purchase_reference: $response.body#/purchase_reference
total: $response.body#/total
batches: $response.body#/batches

As a workflow file

The workflow returns:

purchase_reference: $steps.purchase.outputs.purchase_reference
total: $steps.purchase.outputs.total

Values starting with $ are filled in as you go: $inputs.x is something you provide, $steps.s.outputs.o is a value an earlier step returned, and $response.body#/path a field of this response.

This recipe is the workflow buy_stock of arazzo.json, an Arazzo 1.0 document that tools and AI agents can follow step by step.