---
title: "Prepare a US/USD purchase within this card's existing permissions and spending limits. Amounts are integer USD cents. Card issuing is stubbed: no order or payment is submitted. Returns a durable purchase ID; poll get_purchase, never create another purchase to poll."
method: POST
path: "/v1/purchase"
---

# Prepare a US/USD purchase within this card's existing permissions and spending limits. Amounts are integer USD cents. Card issuing is stubbed: no order or payment is submitted. Returns a durable purchase ID; poll get_purchase, never create another purchase to poll.

`POST /v1/purchase`

## Request

- Base URL: `http://localhost:5100`
- URL: `http://localhost:5100/v1/purchase`
- Auth: HTTP bearer

## Request body

- object
  - `idempotencyKey` string, required
  - `url` string, uri, required
  - `item` string, required
  - `quantity` integer
  - `options` object
  - `maxTotalMinor` string, required
  - `currency` 'USD'
  - `country` 'US'
  - `details` object
    - `email` string, email
    - `phone` string
    - `shipping` object
      - `name` string, required
      - `line1` string, required
      - `line2` string
      - `city` string, required
      - `state` string, required
      - `postalCode` string, required
      - `country` 'US', required
    - `billing` object
      - `name` string, required
      - `line1` string, required
      - `line2` string
      - `city` string, required
      - `state` string, required
      - `postalCode` string, required
      - `country` 'US', required
    - `deliveryInstructions` string
    - `itemInstructions` string
    - `service` object
      - `account` string
      - `activationEmail` string, email
      - `seats` integer
      - `startsAt` string, date-time
  - `profileId` string, uuid
  - `recurring` object
    - `authorized` true, required
    - `maxPeriodMinor` string, required
    - `maxCommitmentMinor` string, required
    - `maxPeriods` integer, required
    - `cadence` 'month' | 'year', required
  - `cardId` string, uuid: Card to use. Required when this connection has multiple cards. List cards first.

## Response `200`

Operation result. An invocation may still be pending; inspect its state.

- unknown

## Other responses

- `400`: Rejected request or temporary failure. See the errors and limits guide.
- `402`: Rejected request or temporary failure. See the errors and limits guide.
- `403`: Rejected request or temporary failure. See the errors and limits guide.
- `404`: Rejected request or temporary failure. See the errors and limits guide.
- `409`: Rejected request or temporary failure. See the errors and limits guide.
- `503`: Rejected request or temporary failure. See the errors and limits guide.

---

[API](https://skmtc.dev/o11/apis/o11-wallet-api.md) - [All operations](https://skmtc.dev/o11/apis/o11-wallet-api/llms.txt) - [OpenAPI document](https://skmtc.dev/o11/apis/o11-wallet-api/revisions/2071972de71c?raw)