Developer documentation

Allowance API

The Allowance API lets platforms request customer-approved purchases without collecting, storing, or exposing payment card details.

API access is opening in stages. Join the waitlist.

Setup

Authentication

Send your API key as a Bearer token with every request.

Use an idempotency key for requests that create or change a resource.

Authorization header

Authorization: Bearer ALLOWANCE_API_KEY
Idempotency-Key: 7d8ee2d8-4cd1-4ac7-bf4d-1b47616863bf

API reference

Endpoints

All requests and responses use JSON. Amounts are expressed in cents.

POST /v1/connections

Create a connection

Creates a customer connection for your platform. Store the returned connection ID with your own customer record.

Params

Parameter	Required	Description
`external_user_id`	Yes	Your stable identifier for this customer.
`email`	No	Customer email for account recovery and notifications.

Example request

POST /v1/connections

curl https://api.allowance.com/v1/connections \
  -H "Authorization: Bearer $ALLOWANCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "external_user_id": "user_123", "email": "customer@example.com" }'

Example response

201 Created

{
  "id": "conn_123",
  "status": "onboarding_required"
}

POST /v1/setup-sessions

Create a setup session

Returns a hosted URL where a customer can sign in, add a payment method, and approve your platform’s connection.

Params

Parameter	Required	Description
`connection_id`	Yes	The customer connection to set up.
`return_url`	Yes	HTTPS URL to open after setup is complete.

Example request

POST /v1/setup-sessions

{
  "connection_id": "conn_123",
  "return_url": "https://example.com/allowance/complete"
}

Example response

201 Created

{
  "id": "set_123",
  "url": "https://app.useallowance.com/setup/set_123"
}

POST /v1/purchases

Create a purchase

Requests permission for one purchase. Allowance checks the customer’s rules and returns the next action.

Params

Parameter	Required	Description
`connection_id`	Yes	The customer making the purchase.
`merchant`	Yes	Name of the merchant.
`max_total_cents`	Yes	Maximum amount the customer authorizes.
`currency`	Yes	Three-letter ISO currency code.

Example request

POST /v1/purchases

{
  "connection_id": "conn_123",
  "merchant": "Example Store",
  "max_total_cents": 5000,
  "currency": "usd"
}

Example response

201 Created

{
  "id": "pur_123",
  "status": "requires_approval",
  "approval_url": "https://app.useallowance.com/approve/pur_123"
}

GET /v1/purchases/:id

Retrieve a purchase

Returns the current state of a purchase request. Use this to check whether a customer has completed approval.

Params

Parameter	Required	Description
`id`	Yes	The purchase ID returned when the purchase was created.

Example request

GET /v1/purchases/pur_123

curl https://api.allowance.com/v1/purchases/pur_123 \
  -H "Authorization: Bearer $ALLOWANCE_API_KEY"

Example response

200 OK

{
  "id": "pur_123",
  "status": "approved",
  "max_total_cents": 5000,
  "currency": "usd"
}

Get API access

Join the waitlist and tell us what you’re building.

Join the waitlist