Development
  • Guides
  • API Reference
  • API Explorer
  • SDKs
  • Sample apps
  • System status
Support
  • Developer forums
  • Developer blog
  • YouTube
  • X
More
  • Square Home
  • Square Developer
  • App Marketplace
  • Partner with Square
  • Solutions Partner Program
  • Pricing
  • Sales

© 2026 Square, Inc.

  • Developer terms of service
  • Developer Integration and Marketing Agreement
  • Privacy policy
  • Partnerships
  • Sign In
  • Sign In

    Subscriptions

  • Create subscription

  • Bulk swap plan

  • Search subscriptions

  • Retrieve subscription

  • Update subscription

  • Delete subscription action

  • Change billing anchor date

  • Cancel subscription

  • List subscription events

  • Pause subscription

  • Resume subscription

  • Swap plan

  • Webhooks

  • subscription.created

  • subscription.updated

<- Subscriptions API

Subscriptions API

All versions ->

Update subscription

PUT

 /v2/subscriptions/{subscription_id}

Updates a subscription by modifying or clearing subscription field values.

To clear a field, set its value to null.

Permissions:CUSTOMERS_READ, INVOICES_WRITE, ITEMS_READ, ORDERS_WRITE, PAYMENTS_WRITE, SUBSCRIPTIONS_WRITE

Guide

Update Subscriptions

Try in API Explorer
Link to section

Path parameters

Example code

Link to section

subscription_id

string

Required

The ID of the subscription to update.

Link to section

Request body

Link to section

subscription

The subscription object containing the current version, and fields to update. Unset fields will be left at their current server values, and JSON null values will be treated as a request to clear the relevant data.

Link to section

Response fields

Link to section

errors

Errors encountered during the request.

Link to section

subscription

The updated subscription.

Link to section

Examples

All versions ->

PUT /v2/subscriptions/{subscription_id}
curl https://connect.squareup.com/v2/subscriptions/7217d8ca-1fee-4446-a9e5-8540b5d8c9bb \ -X PUT \ -H 'Square-Version: 2026-09-16' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "subscription": { "card_id": "{NEW CARD ID}", "canceled_date": null } }'

Response JSON

{ "subscription": { "id": "7217d8ca-1fee-4446-a9e5-8540b5d8c9bb", "location_id": "LPJKHYR7WFDKN", "plan_variation_id": "XOUNEKCE6NSXQW5NTSQ73MMX", "customer_id": "AM69AB81FT4479YH9HGWS1HZY8", "start_date": "2023-01-30", "charged_through_date": "2023-03-13", "card_id": "{NEW CARD ID}", "status": "ACTIVE", "invoice_ids": [ "inv:0-ChAPSfVYvNewckgf3x4iigN_ENMM", "inv:0-ChBQaCCLfjcm9WEUBGxvuydJENMM" ], "version": 3, "created_at": "2023-01-30T19:27:32Z", "timezone": "UTC", "source": { "name": "My Application" } } }

Error descriptions

400 Bad request

{ "errors": [ { "code": "CUSTOMER_NOT_FOUND", "category": "INVALID_REQUEST_ERROR" } ] }