---
title: "Set default payment method"
method: PUT
path: "/subscriptions/{subscriptionId}/paymentmethods"
tags: ["Subscription Payments"]
---

# Set default payment method

`PUT /subscriptions/{subscriptionId}/paymentmethods`

## Request

- Base URL: `https://api.smokeball.com`
- URL: `https://api.smokeball.com/subscriptions/{subscriptionId}/paymentmethods`
- Auth: API key in header `x-api-key` and API key in header `Authorization`

Sets or clears the default payment method on a subscription. The update is processed asynchronously.
            
Important considerations:
* Omitting the payment method id clears the subscription's default payment method
* Usage subscriptions must always have a default payment method, so clearing is not allowed for them
* For a usage subscription that doesn't exist yet, the payment method is kept and set as its default when it is created

## Path parameters

- `subscriptionId` string, required

## Request body

- SetDefaultPaymentMethodRequest: Request to set or clear a subscription default payment method.
  - `paymentMethodId` string, uuid, nullable: Public payment method id. Null clears the subscription override which reverts behavior to the Customer's default.
  - `subscriptionType` 0 | 1

## Response `202`

When request is accepted. Returns a 'Link' object to the payment method, or to the subscription when clearing.

- Link
  - `id` string, nullable
  - `href` string, nullable
  - `relation` string, nullable
  - `method` string, nullable

## Other responses

- `400`: When clearing the default on a usage subscription, or the subscription is not associated to a customer.
- `404`: When the subscription or payment method does not exist.
- `500`: When an error occurs while updating the payment method.

---

[API](https://skmtc.dev/smokeball/apis/smokeball-api.md) - [All operations](https://skmtc.dev/smokeball/apis/smokeball-api/llms.txt) - [OpenAPI document](https://skmtc.dev/smokeball/apis/smokeball-api/revisions/6e350cf667d4?raw)