Skip to content
ApiqDevelopers
API v1.64.0Open console
API referencepayments

Set default payment method

POST/v1/payments/methods/{methodId}:make-default
Idempotency-Key requiredAccepts bearer

Make a saved payment method the default

The ':make-default' literal-suffix custom method.Show moreThe ':make-default' literal-suffix custom method. The default is what a SAVED_METHOD order charges when it names no methodId, and what the console's review-and-pay step preselects. Making the default the default again is a 200 no-op. An unknown id and another tenant's id are the same 404 NOT_FOUND. Human session only; Owner only (403 PERMISSION_DENIED details.reason OWNER_ONLY). Idempotency-Key required. Audited (payments.method_default_set).

Path parameters

  • methodIdstringRequired
    A saved payment method's id (SavedPaymentMethod.id)

Headers

  • Idempotency-KeystringRequired
    Mandatory on mutations: **48h TTL**; replay with same body-hash returns the original response with Idempotency-Replayed true; same key + different body is 409 IDEMPOTENCY_CONFLICT; in-flight duplicate…Show moreMandatory on mutations: **48h TTL**; replay with same body-hash returns the original response with Idempotency-Replayed true; same key + different body is 409 IDEMPOTENCY_CONFLICT; in-flight duplicate is 409 IDEMPOTENCY_IN_PROGRESS.

Request body

This operation takes no request body.

Responses

  • 200The method, now the defaultSavedPaymentMethod
  • 401
    UNAUTHENTICATED — missing or expired token.Show moreUNAUTHENTICATED — missing or expired token. Declared on every operation because `security` is declared globally at the document root: every route is authenticated, so every route can answer 401.
    ApiErrorResponse
  • 403ApiErrorResponse
  • 404NOT_FOUND — unknown or expired ref (unguessable refs, 15)ApiErrorResponse
  • 405
    VALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge).Show moreVALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge). Not retryable as sent.
    ApiErrorResponse
  • 409IDEMPOTENCY_CONFLICT | IDEMPOTENCY_IN_PROGRESS — the only 409s of a mutation with no domain conflictApiErrorResponse
  • 414
    VALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge).Show moreVALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge). Not retryable as sent: send long input in the body of a POST.
    ApiErrorResponse
  • 500INTERNAL — a bug, and traceId is the support handle.ApiErrorResponse
  • 501
    NOT_IMPLEMENTED PAYMENT_METHODS_UNAVAILABLE — saved payment methods are off on this deployment (aikonic.payment-methods.enabled, off by default, on at DEV and SANDBOX).Show moreNOT_IMPLEMENTED PAYMENT_METHODS_UNAVAILABLE — saved payment methods are off on this deployment (aikonic.payment-methods.enabled, off by default, on at DEV and SANDBOX). Not retryable.
    ApiErrorResponse

Errors you should handle

Branch on code and honour retryable — never on the HTTP status alone.

401UNAUTHENTICATED
The bearer token is expired. Re-authenticate and retry.
not retryable
403PERMISSION_DENIED
Reading wallets needs the finance:read permission.
not retryable
404NOT_FOUND
searchRef SR-F-7b31d0a9 is unknown or has expired; re-search
not retryable
405VALIDATION
This method is not served.
not retryable
409IDEMPOTENCY_CONFLICT
Idempotency-Key 7f0c33d1-9a1e-4d2c-9f77-1c0f2b3a4d55 was used with a different body; never executed
not retryable
409IDEMPOTENCY_IN_PROGRESS
A request with this Idempotency-Key is still executing
retryable
414VALIDATION
The request URI is longer than 8 KiB.
not retryable
500INTERNAL
An unexpected error occurred. Quote the traceId to support.
retryable
501NOT_IMPLEMENTED
Saved payment methods are not available on this deployment.
not retryable