Skip to main content
The Subscriptions API enables you to create and manage recurring payment subscriptions for your customers. Use this API to set up subscription plans, manage customer subscriptions, and handle billing cycles.

​
Available Methods

The Subscriptions client provides the following methods:
  • CreateSubscription - Create a new subscription for a customer
  • SearchSubscriptions - Search for subscriptions with filters
  • GetSubscription - Retrieve a subscription by ID
  • UpdateSubscription - Update an existing subscription
  • CancelSubscription - Cancel a subscription
  • PauseSubscription - Temporarily pause a subscription
  • ResumeSubscription - Resume a paused subscription
  • SwapPlan - Change a subscription’s plan
  • BulkSwapPlan - Change plans for multiple subscriptions
  • ChangeBillingAnchorDate - Change the billing anchor date
  • DeleteSubscriptionAction - Delete a scheduled action
  • ListSubscriptionEvents - List events for a subscription

​
Create Subscription

Creates a subscription to a subscription plan by a customer. The required input includes the plan variation ID, customer ID, and location ID. 
package main

import (
    "context"
    "fmt"
    "github.com/square/square-go-sdk/v3"
)

func main() {
    client := square.NewClient(
        square.WithAccessToken("YOUR_ACCESS_TOKEN"),
    )

    request := &square.CreateSubscriptionRequest{
        IdempotencyKey: square.String("8193148c-9586-11e6-99f9-28cfe92138cf"),
        LocationID: "S8GWD5R9QB376",
        PlanVariationID: square.String("6JHXF3B2CW3YKHDV4XEM674H"),
        CustomerID: "CHFGVKYY8RSV93M5KCYTG4PN0G",
        StartDate: square.String("2023-06-20"),
        TaxPercentage: square.String("5"),
        PriceOverrideMoney: &square.Money{
            Amount: square.Int64(2000),
            Currency: square.CurrencyUsd.Ptr(),
        },
        CardID: square.String("ccof:customer-card-id"),
        Timezone: square.String("America/Los_Angeles"),
    }

    response, err := client.Subscriptions.CreateSubscription(context.Background(), request)
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }

    fmt.Printf("Subscription created: %s\n", *response.Subscription.ID)
}

​
Parameters

​
LocationID
string
required
The ID of the location the subscription is associated with
​
PlanVariationID
*string
The ID of the subscription plan variation created using the Catalog API
​
CustomerID
string
required
The ID of the customer subscribing to the subscription plan variation
​
IdempotencyKey
*string
A unique string that identifies this CreateSubscription request. See Idempotency for more information.
​
StartDate
*string
The YYYY-MM-DD-formatted date to start the subscription. If it is unspecified, the subscription starts immediately.
​
CanceledDate
*string
The YYYY-MM-DD-formatted date when the newly created subscription is scheduled for cancellation
​
TaxPercentage
*string
The tax to add when billing the subscription. The percentage is expressed in decimal form, using a ’.’ as the decimal separator and without a ’%’ sign.
​
PriceOverrideMoney
*square.Money
A custom price which overrides the cost of a subscription plan variation with STATIC pricing
​
CardID
*string
The ID of the subscriber’s card to charge. If it is not specified, the subscriber receives an invoice via email with a link to pay for their subscription.
​
Timezone
*string
The timezone that is used in date calculations for the subscription. Format: the IANA Timezone Database identifier for the location timezone.
​
Source
*square.SubscriptionSource
The origination details of the subscription
​
MonthlyBillingAnchorDate
*int
The day-of-the-month to change the billing date to
​
Phases
[]*square.Phase
Array of phases for this subscription

​
Response

​
Subscription
*square.Subscription
The newly created subscription. For more information, see the Subscription object.
​
Errors
[]*square.Error
Errors encountered during the request

​
Search Subscriptions

Searches for subscriptions with filtering and sorting options. Returns a paginated list of subscriptions. 
package main

import (
    "context"
    "fmt"
    "github.com/square/square-go-sdk/v3"
)

func main() {
    client := square.NewClient(
        square.WithAccessToken("YOUR_ACCESS_TOKEN"),
    )

    request := &square.SearchSubscriptionsRequest{
        Query: &square.SearchSubscriptionsQuery{
            Filter: &square.SearchSubscriptionsFilter{
                CustomerIDs: []string{"CHFGVKYY8RSV93M5KCYTG4PN0G"},
                LocationIDs: []string{"S8GWD5R9QB376"},
            },
        },
        Limit: square.Int(10),
        Include: []string{"actions"},
    }

    response, err := client.Subscriptions.SearchSubscriptions(context.Background(), request)
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }

    fmt.Printf("Found %d subscriptions\n", len(response.Subscriptions))
}

​
Parameters

​
Query
*square.SearchSubscriptionsQuery
A subscription query consisting of specified filtering conditions. If this query field is unspecified, the SearchSubscriptions call will return all subscriptions.
​
Limit
*int
The upper limit on the number of subscriptions to return in a paged response
​
Cursor
*string
When the total number of resulting subscriptions exceeds the limit of a paged response, specify the cursor returned from a preceding response to fetch the next set of results.
​
Include
[]string
An option to include related information in the response. The supported values are: actions - to include scheduled actions on the targeted subscriptions.

​
Response

​
Subscriptions
[]*square.Subscription
The subscriptions matching the query
​
Cursor
*string
The pagination cursor to retrieve the next set of results
​
Errors
[]*square.Error
Errors encountered during the request

​
Get Subscription

Retrieves a specific subscription by ID. 
package main

import (
    "context"
    "fmt"
    "github.com/square/square-go-sdk/v3"
)

func main() {
    client := square.NewClient(
        square.WithAccessToken("YOUR_ACCESS_TOKEN"),
    )

    request := &square.GetSubscriptionsRequest{
        SubscriptionID: "8151d94c-5c8e-4fd1-8e45-63716b49e7ab",
        Include: square.String("actions"),
    }

    response, err := client.Subscriptions.GetSubscription(context.Background(), request)
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }

    fmt.Printf("Subscription: %s\n", *response.Subscription.ID)
}

​
Parameters

​
SubscriptionID
string
required
The ID of the subscription to retrieve
​
Include
*string
A query parameter to specify related information to be included in the response. Supported values: actions - to include scheduled actions on the targeted subscription.

​
Response

​
Subscription
*square.Subscription
The requested subscription
​
Errors
[]*square.Error
Errors encountered during the request

​
Cancel Subscription

Schedules a subscription for cancellation. The subscription continues until the end of the current billing cycle. 
package main

import (
    "context"
    "fmt"
    "github.com/square/square-go-sdk/v3"
)

func main() {
    client := square.NewClient(
        square.WithAccessToken("YOUR_ACCESS_TOKEN"),
    )

    request := &square.CancelSubscriptionsRequest{
        SubscriptionID: "8151d94c-5c8e-4fd1-8e45-63716b49e7ab",
    }

    response, err := client.Subscriptions.CancelSubscription(context.Background(), request)
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }

    fmt.Printf("Subscription canceled: %s\n", *response.Subscription.ID)
}

​
Parameters

​
SubscriptionID
string
required
The ID of the subscription to cancel

​
Response

​
Subscription
*square.Subscription
The specified subscription scheduled for cancellation according to the action created by the request
​
Actions
[]*square.SubscriptionAction
A list of a single CANCEL action scheduled for the subscription
​
Errors
[]*square.Error
Errors encountered during the request

​
Pause Subscription

Pauses a subscription. The subscription is paused at the beginning of the next billing cycle. 
package main

import (
    "context"
    "fmt"
    "github.com/square/square-go-sdk/v3"
)

func main() {
    client := square.NewClient(
        square.WithAccessToken("YOUR_ACCESS_TOKEN"),
    )

    request := &square.PauseSubscriptionRequest{
        SubscriptionID: "8151d94c-5c8e-4fd1-8e45-63716b49e7ab",
        PauseEffectiveDate: square.String("2023-07-01"),
        PauseReason: square.String("Customer requested pause"),
    }

    response, err := client.Subscriptions.PauseSubscription(context.Background(), request)
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }

    fmt.Printf("Subscription paused: %s\n", *response.Subscription.ID)
}

​
Parameters

​
SubscriptionID
string
required
The ID of the subscription to pause
​
PauseEffectiveDate
*string
The YYYY-MM-DD-formatted date when the scheduled PAUSE action takes place on the subscription. When this date is unspecified or falls within the current billing cycle, the subscription is paused on the starting date of the next billing cycle.
​
PauseCycleDuration
*int64
The number of billing cycles the subscription will be paused before it is reactivated
​
ResumeEffectiveDate
*string
The date when the subscription is reactivated by a scheduled RESUME action
​
ResumeChangeTiming
*square.ChangeTiming
The timing whether the subscription is reactivated immediately or at the end of the billing cycle, relative to resume_effective_date
​
PauseReason
*string
The user-provided reason to pause the subscription

​
Response

​
Subscription
*square.Subscription
The paused subscription
​
Actions
[]*square.SubscriptionAction
The list of a PAUSE and/or RESUME actions created for the subscription
​
Errors
[]*square.Error
Errors encountered during the request

​
Resume Subscription

Resumes a paused subscription. The subscription is resumed at the beginning of the specified billing cycle. 
package main

import (
    "context"
    "fmt"
    "github.com/square/square-go-sdk/v3"
)

func main() {
    client := square.NewClient(
        square.WithAccessToken("YOUR_ACCESS_TOKEN"),
    )

    request := &square.ResumeSubscriptionRequest{
        SubscriptionID: "8151d94c-5c8e-4fd1-8e45-63716b49e7ab",
        ResumeEffectiveDate: square.String("2023-08-01"),
        ResumeChangeTiming: square.ChangeTimingImmediate.Ptr(),
    }

    response, err := client.Subscriptions.ResumeSubscription(context.Background(), request)
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }

    fmt.Printf("Subscription resumed: %s\n", *response.Subscription.ID)
}

​
Parameters

​
SubscriptionID
string
required
The ID of the subscription to resume
​
ResumeEffectiveDate
*string
The YYYY-MM-DD-formatted date when the subscription reactivated
​
ResumeChangeTiming
*square.ChangeTiming
The timing to resume a subscription, relative to the specified resume_effective_date attribute value

​
Response

​
Subscription
*square.Subscription
The resumed subscription
​
Actions
[]*square.SubscriptionAction
The list of a RESUME action created for the subscription
​
Errors
[]*square.Error
Errors encountered during the request

​
Swap Plan

Changes the subscription plan for a subscription. The new plan takes effect at the next billing date. 
package main

import (
    "context"
    "fmt"
    "github.com/square/square-go-sdk/v3"
)

func main() {
    client := square.NewClient(
        square.WithAccessToken("YOUR_ACCESS_TOKEN"),
    )

    request := &square.SwapPlanRequest{
        SubscriptionID: "8151d94c-5c8e-4fd1-8e45-63716b49e7ab",
        NewPlanVariationID: square.String("FQ7CNXXN2FZPK6FJF2QYMVZQ"),
    }

    response, err := client.Subscriptions.SwapPlan(context.Background(), request)
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }

    fmt.Printf("Plan swapped for subscription: %s\n", *response.Subscription.ID)
}

​
Parameters

​
SubscriptionID
string
required
The ID of the subscription to swap the subscription plan for
​
NewPlanVariationID
*string
required
The ID of the new subscription plan variation. This field is required.
​
Phases
[]*square.PhaseInput
A list of PhaseInputs, to pass phase-specific information used in the swap

​
Response

​
Subscription
*square.Subscription
The subscription with the swapped plan
​
Actions
[]*square.SubscriptionAction
The list of a SWAP_PLAN action created for the subscription
​
Errors
[]*square.Error
Errors encountered during the request

​
Bulk Swap Plan

Swaps the plan for multiple subscriptions. Active subscriptions using the old plan variation will be subscribed to the new plan variation on their next billing day. 
package main

import (
    "context"
    "fmt"
    "github.com/square/square-go-sdk/v3"
)

func main() {
    client := square.NewClient(
        square.WithAccessToken("YOUR_ACCESS_TOKEN"),
    )

    request := &square.BulkSwapPlanRequest{
        NewPlanVariationID: "FQ7CNXXN2FZPK6FJF2QYMVZQ",
        OldPlanVariationID: "6JHXF3B2CW3YKHDV4XEM674H",
        LocationID: "S8GWD5R9QB376",
    }

    response, err := client.Subscriptions.BulkSwapPlan(context.Background(), request)
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }

    fmt.Printf("Swapped plans for %d subscriptions\n", *response.AffectedSubscriptions)
}

​
Parameters

​
NewPlanVariationID
string
required
The ID of the new subscription plan variation. This field is required.
​
OldPlanVariationID
string
required
The ID of the plan variation whose subscriptions should be swapped
​
LocationID
string
required
The ID of the location to associate with the swapped subscriptions

​
Response

​
AffectedSubscriptions
*int
The number of affected subscriptions
​
Errors
[]*square.Error
Errors encountered during the request

Build docs developers (and LLMs) love

Get started for freeTalk to us