SellApp
API ReferenceWallet

Retrieve a customer wallet

Retrieve a wallet by its current-store customer ID.

Read balance_cents, held_cents, and available_cents as integer USD cents. Held funds belong to unexpired checkout reservations; available funds are the balance minus those holds, never below zero. A frozen wallet cannot spend its available balance.

The transactions endpoint returns the complete history newest first, 15 entries per page by default (up to 100). Follow links.next until it is null. An existing wallet with no entries returns data: []; an unknown wallet returns 404. Each entry identifies its type, signed amount, resulting balance, and available order/charge or reversal references. Positive amounts credit the wallet and negative amounts debit it.

GET
/v2/wallets/{customer}

Retrieve one current-store customer wallet by customer ID. OAuth callers use the admin grant and select a store with X-STORE. Current membership and role permissions apply to every request.

Authorization

AuthorizationBearer <token>

Provide your SellApp API key as a bearer token.

In: header

Path Parameters

customer*integer

The customer path parameter.

Header Parameters

X-STORE?string

Store slug. Required for OAuth access tokens. API keys may omit it to use their current store, or the first accessible store when no current store is selected.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://sell.app/api/v2/wallets/0" \  -H "X-STORE: launch-lab"
{
  "data": {
    "id": 70,
    "customer_id": 77,
    "customer_email": "maya@example.com",
    "balance_cents": 2500,
    "status": "active",
    "created_at": "2026-09-01T12:00:00Z",
    "updated_at": "2026-09-01T12:00:00Z"
  }
}
{
  "type": "invalid_request_error",
  "code": "bad_request",
  "message": "The request could not be understood.",
  "status": 400,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#bad-request"
}
{
  "type": "authentication_error",
  "code": "unauthenticated",
  "message": "Unauthenticated.",
  "status": 401,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#unauthenticated"
}
{
  "type": "authorization_error",
  "code": "forbidden",
  "message": "This action is unauthorized.",
  "status": 403,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#forbidden"
}
{
  "type": "not_found_error",
  "code": "resource_not_found",
  "message": "Not Found.",
  "status": 404,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#resource-not-found"
}
{
  "type": "validation_error",
  "code": "validation_failed",
  "message": "The selected product variant id is invalid.",
  "status": 422,
  "param": "product_variant_id",
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#validation-failed",
  "errors": {
    "product_variant_id": [
      "The selected product variant id is invalid."
    ]
  }
}
{
  "type": "rate_limit_error",
  "code": "rate_limit_exceeded",
  "message": "Too Many Attempts.",
  "status": 429,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#rate-limit-exceeded"
}
{
  "type": "api_error",
  "code": "api_error",
  "message": "Server Error",
  "status": 500,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#api-error"
}
GET
/v2/wallets/{customer}/transactions

Read the complete wallet history for one customer in the selected store, newest first. Requires the wallet or wallet:write API-key ability and store wallet permission. Amounts and balances are integer USD cents: 2500 means $25.00. A wallet with no entries returns an empty data array; an unknown wallet returns 404. OAuth callers use the admin grant and select a store with X-STORE. Current membership and role permissions apply to every request.

Authorization

AuthorizationBearer <token>

Provide your SellApp API key as a bearer token.

In: header

Path Parameters

customer*integer

Query Parameters

page?integer
Default1
Range1 <= value
limit?integer
Default15
Range1 <= value <= 100

Header Parameters

X-STORE?string

Store slug. Required for OAuth access tokens. API keys may omit it to use their current store, or the first accessible store when no current store is selected.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://sell.app/api/v2/wallets/42/transactions?page=1&limit=15" \  -H "X-STORE: launch-lab"
{
  "data": [],
  "links": {
    "first": "https://sell.app/api/v2/wallets/42/transactions?page=1",
    "last": "https://sell.app/api/v2/wallets/42/transactions?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "links": [],
    "current_page": 1,
    "from": null,
    "last_page": 1,
    "path": "https://sell.app/api/v2/wallets/42/transactions",
    "per_page": 15,
    "to": null,
    "total": 0
  }
}
{
  "type": "invalid_request_error",
  "code": "bad_request",
  "message": "The request could not be understood.",
  "status": 400,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#bad-request"
}
{
  "type": "authentication_error",
  "code": "unauthenticated",
  "message": "Unauthenticated.",
  "status": 401,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#unauthenticated"
}
{
  "type": "authorization_error",
  "code": "forbidden",
  "message": "This action is unauthorized.",
  "status": 403,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#forbidden"
}
{
  "type": "not_found_error",
  "code": "resource_not_found",
  "message": "Not Found.",
  "status": 404,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#resource-not-found"
}
{
  "type": "validation_error",
  "code": "validation_failed",
  "message": "The selected product variant id is invalid.",
  "status": 422,
  "param": "product_variant_id",
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#validation-failed",
  "errors": {
    "product_variant_id": [
      "The selected product variant id is invalid."
    ]
  }
}
{
  "type": "rate_limit_error",
  "code": "rate_limit_exceeded",
  "message": "Too Many Attempts.",
  "status": 429,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#rate-limit-exceeded"
}
{
  "type": "api_error",
  "code": "api_error",
  "message": "Server Error",
  "status": 500,
  "param": null,
  "request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
  "docs_url": "https://sell.app/docs/api/errors#api-error"
}

List customer wallets GET

List current-store customer wallet balances.

Create a wallet top-up payment link POST

Create a USD payment link for a customer to fund their wallet.